Xacro Development and Troubleshooting

Xacro doesn't generate a valid robot_description in MoveIt Pro

Problem: During development of a new configuration package, the robot_description can fail to be generated with the following error if there are problems with one or more of the xacro files, like such:

[waypoint_manager_node-3] [ERROR] [1725641580.482433533] [waypoint_manager_node]: Could not find parameter robot_description and did not receive robot_description via std_msgs::msg::String subscription within 10.000000 seconds.
[move_group-1] [ERROR] [1725641580.520048163] [move_group]: Could not find parameter robot_description and did not receive robot_description via std_msgs::msg::String subscription within 10.000000 seconds.
[waypoint_manager_node-3] Error:   Error document empty.
[waypoint_manager_node-3]          at line 100 in ./urdf_parser/src/model.cpp
[waypoint_manager_node-3] Failed to parse robot description using: urdf_xml_parser/URDFXMLParser
[waypoint_manager_node-3] [ERROR] [1725641580.646472353] [waypoint_manager_node.moveit.ros.planning_scene_monitor]: Robot model not loaded
[move_group-1] Error:   Error document empty.
[move_group-1]          at line 100 in ./urdf_parser/src/model.cpp
[move_group-1] Failed to parse robot description using: urdf_xml_parser/URDFXMLParser

Or, there are problems with the URDF parameters in the config.yaml.

agent_bridge-1  | [ERROR] [launch]: Caught exception in launch (see debug for traceback): launch_setup() missing 1 required positional argument: 'params'

Solution: Follow the steps listed below to verify specific parts are working as intended.

URDF not generated from input Xacro file

Problem: The given Xacro file does not generate a proper complete robot.urdf.

Solution: Utilize the MoveIt Pro Xacro to URDF helper script

This first script makes sure that the URDF can be generated from your given Xacros. If your URDF builds correctly and you are using the URDF path configured in config.yaml, this step can be safely skipped.

Run this inside a container (even if Pro isn't running yet) by:

moveit_pro dev
$ ros2 run moveit_studio_utils_py xacro_to_urdf

If not using the URDF path specified in the MoveIt Pro config.yaml, enter the path to your xacro file when prompted, leaving blank otherwise.

This will create a URDF file (named full.urdf) from your Xacros while taking into account the MoveIt Pro config.yaml parameters.

Finally, an XML linter can check that the resulting URDF file is valid XML, as sometimes characters such as > can appear due to the xacro command and cause issues with the MoveIt Pro parser.

URDF file is generated but invalid

Problem: The robot_description still fails to come up after the URDF file is generated.

Solution: Test the generated URDF file using the check_urdf script.

Next, you can verify that the URDF is valid by using a built in helper script inside MoveIt Pro:

check_urdf full.urdf

This command will inform you if you have an invalid link chain or are otherwise creating an improper TF tree. Once the URDF is valid you will see output indicating success similar to the following:

robot name is: astrobee
---------- Successfully Parsed XML ---------------
root Link: body has 3 child(ren)
    child(1):  bot_aft
        child(1):  bot_aft_arm_proximal_link
            child(1):  bot_aft_arm_distal_link
                child(1):  bot_aft_gripper_left_proximal_link
                    child(1):  bot_aft_gripper_left_distal_link
                child(2):  bot_aft_gripper_right_proximal_link
                    child(1):  bot_aft_gripper_right_distal_link
                child(3):  grasp_link
    child(2):  carriage
    child(3):  inertial_link  

A typical error revealed during this step is an incomplete TF tree, which can be diagnosed as such:

ros2 run tf2_tools view_frames

Which will result in a pdf showing the TF frame tree. This tree should be validated against the actual structure of the robot.

Once this step is complete, any remaining errors are typically due to incorrect paths to media resources and other similar issues.

URDF file is valid but robot_description still does not come up correctly

Problem: The URDF has been confirmed to be valid, but the robot_description still doesn't appear or otherwise is broken.

Solution: Use the troubleshoot_urdf_rviz.launch.py script. Issues with the SRDF and URDF robot_description can be checked utilizing RVIZ with a built in Launchfile:

ros2 launch moveit_studio_agent troubleshoot_urdf_rviz.launch.py

If not using the default URDF path (configured in the config.yaml), enter the path to the desired URDF file when prompted, leaving it blank otherwise. This launch file will also use the processed SRDF (configured in the config.yaml) as needed, helping to verify errors there.

This should visualize your robot model in RVIZ with adjustable joint sliders and reveal additional underlying issues.

Once this launch file runs, the URDF is likely valid and remaining errors can be caused by incorrect configurations for ROS 2 control, simulation plugins in the xacros, Waypoints File using a wrong group_name or group names, or other configuration files being misconfigured.

An example of a common bug once the robot_description mostly works could be forgetting to remove previously incorrect link/joint names in the configuration files such as ROS 2 control configurations.

Another common error is setting launch_robot_state_publisher: false in the config.yaml when it should be set to true instead. This will result in no robot_state_description being published, which may be a no-brainer (but it happened to me). Recall that robot_descriptions in ROS 1 are often parameters as opposed to topics and thus not bridged (if using a ROS 1 to ROS 2 bridge).

After this please try to bring up the generated robot_description and diagnose any remaining error messages that appear (such as misconfigurations in the config files) using:

agent_bridge.app